Celestin Apprentice 5

home *** CD-ROM | disk | FTP | other *** search

/ Celestin Apprentice 5 / Apprentice-Release5.iso / Source Code / Libraries / Bitmap Libraries 2.0 / BitMap.txt < prev

Wrap

Text File | 1996-07-08 | 46.0 KB | 1,493 lines | [TEXT/MPS ]

file BitMap.txt Copyright (C) 1996 by John Montbriand. All Rights Reserved. ABOUT BITMAP... Copyright (C) 1996 by John Montbriand. All Rights Reserved. Distribute freely in areas where the laws of copyright apply. Use at your own risk. Do not distribute modified copies. These various BitMap libraries are for free! ABOUT THE AUTHOR... Comments, questions, or suggestions are always welcome. John Montbriand tinyjohn@sasknet.sk.ca P.O. Box. 1133 Saskatoon Saskatchewan Canada S7K 3N2 WHY IS IT FOR FREE? none of your business, but if you have some business for me, I'll see what I can do.. OUTLINE OF TOPICS BITMAPS, WHAT ARE THEY? IMPLEMENTATION NOTES MATERIALS LEGAL STUFF FURTHER REFERENCE SERVICES PROVIDED (OVERVIEW) BE CAREFUL (CAVEATS) OTHER COOL THINGS YOU CAN DO OVERVIEW OF ROUTINES SPECIFIC ROUTINE DESCRIPTIONS BITMAPS, WHAT ARE THEY? Well, they're like little black and white computer screens in memory that you can do drawing in before transfering the images you draw on them to the screen. Drawing things off screen and then placing them on screen creates the feel of instantaneous, flicker free drawing. BitMaps are a data structure used to store black and white images off-screen. You can use quickdraw to draw directly into bitmaps and create images for placement on the screen, or you can take images from the screen, place them in a bitmap, do various transformations to them, and then put them back on the screen. QuickDraw GrafPorts draw into BitMap structures, and, as a matter of fact, all screen drawing on early macintoshes was implemented through BitMaps that were memory mapped to the screen hardware. The big advantage: BitMaps provide a way to do simple high quality graphics while at the same time requiring very little memory. IMPLEMENTATION NOTES This implementation stores each bitmap in a single, contiguous, non-relocatable memory block refered to using a pointer. The first 14 bytes of the memory block contain the Bitmap data structure, while the remaining bytes are used to store the raster data. MATERIALS The BitMap format itself is the copyright property of Apple computer and has been known to the public since 1983. The routines documented herein are the copyright property of John Montbriand. I am making these routines available to the macintosh programming community because I feel it's about time someone did! They're fun, easy to use, and practical. I hope all who find them will use them well. Compiled and tested with MPW C, MWC, SC, MrC, and MPW PPC. LEGAL STUFF These libraries are provided for free and you may use them in any program you make; however, if you're particular about having signed documentation that proves this fact in your posession then, as I would like to ensure these libraries are widely used, I would be glad provide such documents for you. I don't think this is entirly necessary, but I can understand that some folks feel quite strongly about such issues and prefer to do things in writing. If you would like for me to send you a signed document saying that you have license to use these routines in your programs, then send me a couple of bucks to cover postage and handling and I'll send you back a signed letter saying you have license to use these routines in any software you make. I think two or three dollars is fair as I don't really get a big thrill out of printing stuff out and mailing it, and that's usually enough to cover postage to anywhere in the world. I s'pose you'd have to figure out how much it would cost for me to mail a letter to you from here in Canada. FURTHER REFERENCE BitMap.h and BitMap.c contain routines for accessing and manipulating BitMap data stored in pointers. For more information about BitMaps, offscreen drawing, pointers, C, etc.. refer to the following sources: "Bitmaps" (2-9) in the "Basic QuickDraw" chapter of Inside Macintosh: Imaging With QuickDraw by Apple Computer, Inc. Addison-Wesley. A discussion of the Bitmap data structure and how it applies to GrafPorts. "Boolean Transfer Modes With 1-Bit Pixels" (3-8) in the "QuickDraw Drawing" chapter of Inside Macintosh: Imaging With QuickDraw by Apple Computer, Inc. Addison-Wesley. BitMaps are 1-Bit Pixel data structures. This part discusses the various transfer modes you can use while drawing into BitMaps. "Copying Bits Between Graphics Ports" (3-32) in the "QuickDraw Drawing" chapter of Inside Macintosh: Imaging With QuickDraw by Apple Computer, Inc. Addison-Wesley. A discussion of the Bitmap data structure and how it applies to GrafPorts. "Copying Images" (3-112) in the "QuickDraw Drawing" chapter of Inside Macintosh: Imaging With QuickDraw by Apple Computer, Inc. Addison-Wesley. A discussion of the CopyBits routine and the various parameter combinations you can use with it. This is followed by a discussion of the CopyMask routine. Technical note #163 "Adding Color With CopyBits" by Chris Derossi A discussion of how to draw in colour using bitmaps. Technical note #193 "So Many Bitmaps, So Little Time" by Rick Blair A look at the BitMapToRegion routine. Technical note #41 "Drawing Into an Offscreen Bitmap" by Jim Friedlander & Ginger Jernigan A talk about offscreen bitmaps, and how to use them. Inside Macintosh: Memory by Apple Computer, Inc. Addison-Wesley. A discussion of memory managment, pointers, what they are, and how to use them. The C Programming Language 2nd edition by Brian W. Kernighan and Dennis M. Ritchie. Prentice Hall. Comments for the routines provided herein have been included in the file BitMap.h. Also, there is a 411 help file. SERVICES PROVIDED (OVERVIEW) - routines for creating bitmap structures in memory. - rotate functions for rotating bitmaps 90 degrees left and right, - flip functions for flipping bitmap data both vertically and horizontally, - a trace edges routine for tracing the edges of an image, - a rotation routine for rotating a bitmap to a particular angle, - a routine for duplicating bitmaps, - a routine for comparing bitmaps, - routines providing the painbucket tool and lasso tool effects, - transfer routines for transfering bitmap data to and from the PICT format, - a complete set of logical operations on bitmaps, - a complete set of pixel oriented routines for testing, setting, clearing, and toggling individual pixels in bitmaps, - routines and a macro allowing you to quickly and easily draw into bitmaps, - routines for copying bitmap images to the current grafport, BE CAREFUL (CAVEATS) I think these routines are safe to use, but you should do your own testing. I have provided the source code, and if you find any bugs, please let me know right away so I can provide corrections in future versions. I advertise a finder's fee of $10.00 cash for errors in any of my products. OTHER COOL THINGS YOU CAN DO bitmaps provide a convenient, storage efficient way to implement zero - one adjacency matrices that are incredibly useful for working with directed graphs. OVERVIEW OF ROUTINES creating your own bitmaps: BitMap* NewBitMap(short width, short height); void KillBitMap(BitMap* bits); rotating a bitmap image 90 degrees to the left or to the right: BitMap* RotateRight(BitMap* bits); BitMap* RotateLeft(BitMap* bits); flipping a bitmap image horizontally or vertically: BitMap* FlipVertical(BitMap* bits); BitMap* FlipHorizontal(BitMap* bits); rotating a bitmap image to a particular angle: BitMap* RotateBitMap(BitMap* bits, short cx, short cy, Fixed angle); duplicating a bitmap: BitMap* DuplicateBitMap(BitMap* bits); the paint bucket function: BitMap* PaintBucketBitMap(BitMap* bits, short h, short v); the lasso function: BitMap* LassoBitMap(BitMap* bits); the trace edges function: BitMap* TraceBitMap(BitMap* bits); transfer functions for converting to and from the PICT format: BitMap* PICTToBitMap(PicHandle pic); PicHandle BitMapToPICT(BitMap* bits); logical operations on bitmaps: BitMap* BitMapAND(BitMap* a, BitMap* b); BitMap* BitMapOR(BitMap* a, BitMap* b); BitMap* BitMapXOR(BitMap* a, BitMap* b); BitMap* BitMapNOT(BitMap* a); comparison: Boolean EqualBitMaps(BitMap* a, BitMap* b); pixel oriented functions: Boolean BitMapTest(BitMap* bits, short h, short v); void BitMapSet(BitMap* bits, short h, short v); void BitMapClear(BitMap* bits, short h, short v); Boolean BitMapToggle(BitMap* bits, short h, short v); routines for drawing into bitmaps: BitMapPort* NewBMP(BitMap* bits); void DisposeBMP(BitMapPort* bmp); #define WithBitMap(bits, bmp) routines for copying bitmap data: void PlotBitMap(BitMap* bits, short h, short v); a routine for converting pascal strings into bitmaps: BitMap* StringToBitMap(short font, short size, short face, StringPtr s); SPECIFIC ROUTINE DESCRIPTIONS NewBitMap formal declaration: BitMap* NewBitMap(short width, short height); arguments: width the width of the requested bitmap height the height of the requested bitmap return value: a pointer to a Bitmap data structure. if an error occurs, NULL is returned. description: NewBitMap creates a new bitmap pointer with the requested dimensions. The raster data is initialized to zeros, and if there is not enough memory to allocate the bitmap, NewBitMap will return NULL. example application: The following creates a new bitmap pointer 100 pixels wide and 200 pixels tall. { BitMap *the_bits; the_bits = NewBitMap(100, 200); ... notes: You can call DisposePtr to dispose of a bitmap pointer created by NewBitMap. The routine KillBitMap calls DisposePtr. KillBitMap formal declaration: void KillBitMap(BitMap* bits); arguments: bits a bitmap pointer return value: none. description: KillBitMap disposes of a bitmap pointer allocated by one of: NewMacPaintBitMap, NewBitMap, RotateRight, RotateLeft, FlipVertical, FlipHorizontal, RotateBitMap, DuplicateBitMap, PaintBucketBitMap, LassoBitMap, PICTToBitMap, BitMapAND, BitMapOR, BitMapXOR, or BitMapNOT. It's your general all purpose bitmap pointer disposal function. example application: The following creates a new bitmap pointer 100 pixels wide and 200 pixels tall and then disposes of it by calling KillBitMap. { BitMap *the_bits; the_bits = NewBitMap(100, 200); if (the_bits != NULL) { KillBitMap(the_bits); } notes: KillBitMap simply calls DisposePtr. RotateRight formal declaration: BitMap* RotateRight(BitMap* bits); arguments: bits a bitmap pointer return value: a newly created bitmap pointer containing the image from the bitmap pointer parameter rotated 90 degrees to the right. if an error occurs, RotateRight will return the value NULL. description: RotateRight creates a new bitmap containing the image stored in the parameter bitmap pointer rotated 90 degrees to the right. The resulting bitmap is appropriately sized: i.e. if the source bitmap is 100 pixels wide and 200 pixels tall, then the result bitmap pointer will be 200 pixels wide and 100 pixels tall. example application: The example creates a new bitmap pointer containing the image stored in the original bitmap rotated 90 degrees to the right before copying the image to the current grafport. { BitMap *the_bits; BitMap *rotated_bits; Rect bounds; the_bits = NewBitMap(100, 200); if (the_bits != NULL) { /* here we would draw something into the_bits */ rotated_bits = RotateRight(the_bits); if (rotated_bits != NULL) { bounds = (*rotated_bits)->bounds; PlotMap(rotated_bits, 0, 0, srcCopy); KillBitMap(rotated_bits); } KillBitMap(the_bits); } notes: RotateRight takes advantage of certain addressing and indexing possibilities offered by the arrangement of the raster data in memory. It is faster than calling RotateBitMap and specifying a 90 degree angle. RotateLeft formal declaration: BitMap* RotateLeft(BitMap* bits); arguments: bits a bitmap pointer return value: a newly created bitmap pointer containing the image from the bitmap pointer parameter rotated 90 degrees to the left. if an error occurs, RotateLeft will return the value NULL. description: RotateLeft creates a new bitmap containing the image stored in the parameter bitmap pointer rotated 90 degrees to the left. The resulting bitmap is appropriately sized: i.e. if the source bitmap is 100 pixels wide and 200 pixels tall, then the result bitmap pointer will be 200 pixels wide and 100 pixels tall. example application: The example creates a new bitmap pointer containing the image stored in the original bitmap rotated 90 degrees to the left before copying the image to the current grafport. { BitMap *the_bits; BitMap *rotated_bits; Rect bounds; the_bits = NewBitMap(100, 200); if (the_bits != NULL) { /* here we would draw something into the_bits */ rotated_bits = RotateLeft(the_bits); if (rotated_bits != NULL) { bounds = (*rotated_bits)->bounds; PlotMap(rotated_bits, 0, 0, srcCopy); KillBitMap(rotated_bits); } KillBitMap(the_bits); } notes: RotateLeft takes advantage of certain addressing and indexing possibilities offered by the arrangement of the raster data in memory. It is faster than calling RotateBitMap and specifying a -90 degree angle. FlipVertical formal declaration: BitMap* FlipVertical(BitMap* bits); arguments: bits a bitmap pointer return value: a newly created bitmap pointer containing the image from the bitmap pointer parameter flipped upside down. if an error occurs, FlipVertical will return the value NULL. description: FlipVertical creates a new bitmap containing the image stored in the parameter bitmap pointer flipped upside down. The resulting bitmap will be the same size as the original image. example application: The example creates a new bitmap pointer containing the image stored in the original bitmap flipped upside down before copying the new flipped image to the current grafport. { BitMap *the_bits; BitMap *flippin_bits; Rect bounds; the_bits = NewBitMap(100, 200); if (the_bits != NULL) { /* here we would draw something into the_bits */ flippin_bits = FlipVertical(the_bits); if (flippin_bits != NULL) { bounds = (*flippin_bits)->bounds; PlotMap(flippin_bits, 0, 0, srcCopy); KillBitMap(flippin_bits); } KillBitMap(the_bits); } notes: none. FlipHorizontal formal declaration: BitMap* FlipHorizontal(BitMap* bits); arguments: bits a bitmap pointer return value: a newly created bitmap pointer containing the image from the bitmap pointer parameter flipped horizontally. if an error occurs, FlipHorizontal will return the value NULL. description: FlipHorizontal creates a new bitmap containing the image stored in the parameter bitmap pointer flipped horizontally. The resulting bitmap will be the same size as the original image. example application: The example creates a new bitmap pointer containing the image stored in the original bitmap flipped horizontally before copying the new flipped image to the current grafport. { BitMap *the_bits; BitMap *flippin_bits; Rect bounds; the_bits = NewBitMap(100, 200); if (the_bits != NULL) { /* here we would draw something into the_bits */ flippin_bits = FlipHorizontal(the_bits); if (flippin_bits != NULL) { bounds = (*flippin_bits)->bounds; PlotMap(flippin_bits, 0, 0, srcCopy); KillBitMap(flippin_bits); } KillBitMap(the_bits); } notes: none. RotateBitMap formal declaration: BitMap* RotateBitMap(BitMap* bits, short cx, short cy, float angle); arguments: bits a bitmap pointer cx the horizontal center of rotation cy the vertical center of rotation angle the angle (in degrees) to rotate the image. both positive and negative values are ok. This is a floating point number. return value: a newly created bitmap pointer containing the image from the bitmap pointer parameter rotated around the center cx and cy angle degrees. if an error occurs, RotateBitMap will return the value NULL. description: RotateBitMap creates a new bitmap containing the image from the parameter bitmap pointer rotated angle degrees about the center (cx, cy). The resultant bitmap will have the same dimensions as the parameter bitmap regardless of the angle specified. example application: The example creates a new bitmap pointer containing the image stored in the original bitmap rotated 35.5 degrees to the right before copying the rotated image to the current grafport. { BitMap *the_bits; BitMap *round_bits; Rect bounds; the_bits = NewBitMap(100, 200); if (the_bits != NULL) { /* here we would draw something into the_bits */ round_bits = RotateBitMap(the_bits, 50, 100, 35.5); if (round_bits != NULL) { bounds = (*round_bits)->bounds; PlotMap(round_bits, 0, 0, srcCopy); KillBitMap(round_bits); } KillBitMap(the_bits); } notes: The 68k implementation of RotateBitMap has a speedy implementation built on top of the fixed math routines. For more information about fixed math refer to the Mathematical and Logical Utilities chapter of Inside Macintosh: Operating System Utilities. DuplicateBitMap formal declaration: BitMap* DuplicateBitMap(BitMap* bits); arguments: bits a bitmap pointer return value: a newly created bitmap pointer containing an exact duplicate of the bitmap parameter. if an error occurs, DuplicateBitMap will return the value NULL. description: DuplicateBitMap creates a copy of the bitmap parameter. example application: In this example, we make a new bitmap, duplicate it, and then dispose of the resulting bitmaps. { BitMap *the_bits; BitMap *other_bits; the_bits = NewBitMap(100, 200); if (the_bits != NULL) { other_bits = DuplicateBitMap(the_bits); if (other_bits != NULL) { KillBitMap(other_bits); } KillBitMap(the_bits); } notes: none. PaintBucketBitMap formal declaration: BitMap* PaintBucketBitMap(BitMap* bits, short h, short v); arguments: bits a bitmap pointer h the horizontal position to start painting v the vertical position to start painting return value: a newly created bitmap pointer containing an ones in every pixel where paint would not leak out starting from the point (h, v). if an error occurs, PaintBucketBitMap will return the value NULL. description: PaintBucketBitMap works like the paint bucket tool found in most graphical applications. It calls the routine SeedFill and to fill in the image information in the resulting bitmap pointer. example application: In this example, we make a new bitmap and create a mask bitmap using the PaintBucketBitMap routine starting at the point (50,50). { BitMap *the_bits; BitMap *paint_bits; the_bits = NewBitMap(100, 200); if (the_bits != NULL) { /* here, we would normally draw something in the bitmap */ paint_bits = PaintBucketBitMap(the_bits, 50, 50); if (paint_bits != NULL) { KillBitMap(paint_bits); } KillBitMap(the_bits); } notes: PaintBucketBitMap calls SeedFill. For further information about SeedFill refer to page 3-109 in the QuickDraw Drawing chapter of Inside Macintosh: Imaging With QuickDraw. LassoBitMap formal declaration: BitMap* LassoBitMap(BitMap* bits); arguments: bits a bitmap pointer return value: a newly created bitmap pointer containing an ones in every pixel where paint would not leak in from the edges of the bitmap. if an error occurs, LassoBitMap will return the value NULL. description: LassoBitMap works like the lasso bucket tool found in most graphical applications. It calls the routine CalcMask and to fill in the image information in the resulting bitmap pointer. example application: In this example, we make a new bitmap and create a mask bitmap using the LassoBitMap routine. { BitMap *the_bits; BitMap *paint_bits; the_bits = NewBitMap(100, 200); if (the_bits != NULL) { /* here, we would normally draw something in the bitmap */ paint_bits = LassoBitMap(the_bits); if (paint_bits != NULL) { KillBitMap(paint_bits); } KillBitMap(the_bits); } notes: LassoBitMap calls CalcMask. For further information about CalcMask refer to page 3-111 in the QuickDraw Drawing chapter of Inside Macintosh: Imaging With QuickDraw. TraceBitMap formal declaration: BitMap* TraceBitMap(BitMap* bits); arguments: bits a bitmap pointer return value: a newly created bitmap pointer containing containing the original image with the edges traced. if an error occurs, TraceBitMap will return the value NULL. description: TraceBitMap performs the 'trace edges' command found in many graphical applications returning a new bitmap containing the traced image.. example application: In this example, we make a new bitmap and create a new bitmap containing the traced image. { BitMap *the_bits; BitMap *traced_bits; the_bits = NewBitMap(100, 200); if (the_bits != NULL) { /* here, we would normally draw something in the bitmap */ traced_bits = TraceBitMap(the_bits); if (traced_bits != NULL) { KillBitMap(traced_bits); } KillBitMap(the_bits); } notes: none. EqualBitMaps formal declaration: Boolean EqualBitMaps(BitMap* a, BitMap* b); arguments: a a bitmap pointer b a bitmap pointer return value: true or false. description: returns true if the two bitmaps are the same size and contain the same image content. returns false if either bitmap is NULL. example application: In this example, we make a new bitmap and create a two bitmaps and compare them by calling EqualBitMaps. { BitMap *the_bits; BitMap *other_bits; the_bits = NewBitMap(100, 200); if (the_bits != NULL) { other_bits = TraceBitMap(the_bits); if (other_bits != NULL) { /* here, we would normally draw something in the bitmaps */ if (EqualBitMaps(other_bits, the_bits)) { /* they're the same *blink* */ } KillBitMap(other_bits); } KillBitMap(the_bits); } notes: EqualBitMaps takes into account that either bitmap may have different rowBytes values, and the possibility that garbage values may be stored in the unused bits off to the right of the boundary rectangle. PICTToBitMap formal declaration: BitMap* PICTToBitMap(PicHandle pic); arguments: pic a handle to a QuickDraw picture return value: a newly created bitmap pointer containing a black and white representation of the image drawn by the quickdraw picture parameter. if an error occurs, PICTToBitMap will return the value NULL. description: PICTToBitMap creates a new bitmap pointer the using the size information provided in the QuickDraw picture pointer parameter and draws the picture in the bitmap before returning the bitmap. example application: In this example, we call GetPicture to retrieve a picture from a resource file and then we convert it to a bitmap by calling the routine PICTToBitMap. { PicHandle the_picture; BitMap *the_bits; the_picture = GetPicture(128); if (the_picture != NULL) { the_bits = PICTToBitMap(the_picture); if (the_bits != NULL) { /* at this point, the the_bits contains the picture */ KillBitMap(the_bits); } } notes: none. BitMapToPICT formal declaration: PicHandle BitMapToPICT(BitMap* bits); arguments: bits a bitmap pointer return value: a handle to a QuickDraw picture. if an error occurs, the picture's picFrame will be an empty rectangle. description: BitMapToPICT returns a QuickDraw picture that will draw the image stored in the bitmap. BitMapToPICT is the inverse of PICTToBitMap. example application: In this example, we create a bitmap and convert it into a QuickDraw picture. { PicHandle the_picture; BitMap *the_bits; the_bits = NewBitMap(100, 200); if (the_bits != NULL) { the_picture = BitMapToPICT(the_bits); KillBitMap(the_bits); } notes: QuickDraw pictures are a good way to store image data. BitMapAND formal declaration: BitMap* BitMapAND(BitMap* a, BitMap* b); arguments: a a bitmap pointer b a bitmap pointer return value: a bitmap pointer containing the logical result of ANDing the raster data from bitmap a with the raster data from bitmap b. if an error occurs, NULL is returned. description: BitMapAND logically ANDs the raster data of two bitmap pointers returning a new bitmap pointer containing the result. The two parameter bitmaps must have identical dimensions. example application: In this example, we create two bitmaps and AND them together creating a third bitmap. { BitMap *a=NULL, *b=NULL, *c=NULL; a = NewBitMap(100, 100); if (a == NULL) goto my_error_handler; b = NewBitMap(100, 100); if (b == NULL) goto my_error_handler; c = BitMapAND(a, b); if (c == NULL) goto my_error_handler; /* at this point, c contains the result of logically ANDing the bitmaps a and b */ my_error_handler: if (a != NULL) KillBitMap(a); if (b != NULL) KillBitMap(b); if (c != NULL) KillBitMap(c); } notes: useful for calculating the intersection of two sets of bits. BitMapOR formal declaration: BitMap* BitMapOR(BitMap* a, BitMap* b); arguments: a a bitmap pointer b a bitmap pointer return value: a bitmap pointer containing the logical result of ORing the raster data from bitmap a with the raster data from bitmap b. if an error occurs, NULL is returned. description: BitMapOR logically ORs the raster data of two bitmap pointers returning a new bitmap pointer containing the result. The two parameter bitmaps must have identical dimensions. example application: In this example, we create two bitmaps and OR them together creating a third bitmap. { BitMap *a=NULL, *b=NULL, *c=NULL; a = NewBitMap(100, 100); if (a == NULL) goto my_error_handler; b = NewBitMap(100, 100); if (b == NULL) goto my_error_handler; c = BitMapOR(a, b); if (c == NULL) goto my_error_handler; /* at this point, c contains the result of logically ORing the bitmaps a and b */ my_error_handler: if (a != NULL) KillBitMap(a); if (b != NULL) KillBitMap(b); if (c != NULL) KillBitMap(c); } notes: useful for calculating the union of two sets of bits. BitMapXOR formal declaration: BitMap* BitMapXOR(BitMap* a, BitMap* b); arguments: a a bitmap pointer b a bitmap pointer return value: a bitmap pointer containing the logical result of XORing the raster data from bitmap a with the raster data from bitmap b. if an error occurs, NULL is returned. description: BitMapXOR logically XORs the raster data of two bitmap pointers returning a new bitmap pointer containing the result. The two parameter bitmaps must have identical dimensions. example application: In this example, we create two bitmaps and XOR them together creating a third bitmap. { BitMap *a=NULL, *b=NULL, *c=NULL; a = NewBitMap(100, 100); if (a == NULL) goto my_error_handler; b = NewBitMap(100, 100); if (b == NULL) goto my_error_handler; c = BitMapXOR(a, b); if (c == NULL) goto my_error_handler; /* at this point, c contains the result of logically XORing the bitmaps a and b */ my_error_handler: if (a != NULL) KillBitMap(a); if (b != NULL) KillBitMap(b); if (c != NULL) KillBitMap(c); } notes: useful for calculating the difference of two sets of bits. BitMapNOT formal declaration: BitMap* BitMapNOT(BitMap* a); arguments: a a bitmap pointer return value: a bitmap pointer containing the logical result of complementing the raster data from bitmap a. if an error occurs, NULL is returned. description: BitMapNOT returns a new bitmap pointer containing the inverse of the raster image contained in the bitmap pointer a. example application: In this example, we create a bitmap and it's complement. { BitMap *a=NULL, *b=NULL; a = NewBitMap(100, 100); if (a == NULL) goto my_error_handler; b = BitMapNOT(a); if (b == NULL) goto my_error_handler; /* at this point, b contains the compliment of a */ my_error_handler: if (a != NULL) KillBitMap(a); if (b != NULL) KillBitMap(b); } notes: useful for calculating the complement of a set of bits. BitMapTest formal declaration: Boolean BitMapTest(BitMap* bits, short h, short v); arguments: bits a bitmap pointer h the horizontal position of the pixel to test v the vertical position of the pixel to test return value: true if the pixel is 1, false if the pixel is 0. description: BitMapTest tests the value of the pixel at the location (h,v) returning true if the pixel is 1, and false if the pixel is zero. example application: In this example, we create a bitmap and test the pixel located at (25, 32). { BitMap *bits=NULL; bits = NewBitMap(100, 100); if (bits == NULL) goto my_error_handler; .... if (BitMapTest(bits, 25, 32)) { /* the pixel is 1 */ } else { /* the pixel is 0 */ } my_error_handler: if (bits != NULL) KillBitMap(bits); } notes: attempting to test a point outside of the bitmap's bounds will produce unpredictable results. BitMapSet formal declaration: void BitMapSet(BitMap* bits, short h, short v); arguments: bits a bitmap pointer h the horizontal position of the pixel to set v the vertical position of the pixel to set return value: none. description: BitMapSet sets the value of the pixel at the location (h,v) to 1. example application: In this example, we create a bitmap and set the pixel located at (25, 32) to the value 1. { BitMap *bits=NULL; bits = NewBitMap(100, 100); if (bits == NULL) goto my_error_handler; .... BitMapSet(bits, 25, 32); my_error_handler: if (bits != NULL) KillBitMap(bits); } notes: attempting to set a pixel outside of the bitmap's bounds will produce unpredictable results and may even crash your computer by overwriting something important like the operating system or your program or something like that. BitMapClear formal declaration: void BitMapClear(BitMap* bits, short h, short v); arguments: bits a bitmap pointer h the horizontal position of the pixel to set v the vertical position of the pixel to set return value: none. description: BitMapClear clears the value of the pixel at the location (h,v) to 0. example application: In this example, we create a bitmap and set the pixel located at (25, 32) to the value 0. { BitMap *bits=NULL; bits = NewBitMap(100, 100); if (bits == NULL) goto my_error_handler; .... BitMapClear(bits, 25, 32); my_error_handler: if (bits != NULL) KillBitMap(bits); } notes: attempting to clear a pixel outside of the bitmap's bounds will produce unpredictable results and may even crash your computer by overwriting something important like the operating system or your program or something like that. BitMapToggle formal declaration: Boolean BitMapToggle(BitMap* bits, short h, short v); arguments: bits a bitmap pointer h the horizontal position of the pixel to set v the vertical position of the pixel to set return value: a boolean value indicating the state of the pixel after the toggle operation. i.e. if the pixel is set to the value 1, true is returned. If the pixel is set to the value 0, false is returned. description: BitMapToggle inverts the value of the pixel at the location (h,v) returning true if the pixel is set to 1 or false if the pixel is set to 0. example application: In this example, we create a bitmap and invert the pixel located at (25, 32). { BitMap *bits=NULL; bits = NewBitMap(100, 100); if (bits == NULL) goto my_error_handler; .... BitMapToggle(bits, 25, 32); my_error_handler: if (bits != NULL) KillBitMap(bits); } notes: attempting to toggle a pixel outside of the bitmap's bounds will produce unpredictable results and may even crash your computer by overwriting something important like the operating system or your program or something like that. NewBMP formal declaration: BitMapPort* NewBMP(BitMap* bits); arguments: bits a bitmap pointer return value: a pointer to a BitMapPort data structure. if an error occurs, NULL is returned. description: NewBMP is called by the WithBitMap macro and you should never have to call it directly yourself. What it does is it saves the original grafport, and creates a new grafport suitable for drawing into the bitmap. NewBMP should be followed by a call to DisposeBMP which will restore the original grafport, and dispose of the grafport that was created by NewBMP. example application: In this example, we create a bitmap and use the NewBMP to make a grafport. Then we draw into it and call DisposeBMP to deallocate the grafport. { BitMap *bits=NULL; BitMapPort *bmp=NULL; bits = NewBitMap(100, 100); if (bits == NULL) goto my_error_handler; bmp = NewBMP(bits); if (bmp == NULL) goto my_error_handler; /* after NewBMP, the grafport is set to draw into the bitmap */ MoveTo(10,10); LineTo(20,20); DrawString("\pHello World"); my_error_handler: if (bmp != NULL) DisposeBMP(bmp); if (bits != NULL) KillBitMap(bits); } notes: if NewBMP returns a pointer to a BitMapPort, then you must dispose of that pointer with a call to DisposeBMP. DisposeBMP formal declaration: void DisposeBMP(BitMapPort* bmp); arguments: bmp a pointer to a BitMapPort structure allocated by NewBMP return value: none. description: DisposeBMP restores the original grafport and, deallocates the grafport allocated for drawing into the bitmap. The macro WithBitMap calls this routine automatically and you will not normally have to call it directly. example application: see the example in NewBMP. notes: none. WithBitMap formal declaration: MACRO WithBitMap(bits, bmp) { statement... } arguments: bits a bitmap pointer bmp a variable you have declared of type BitMapPort* return value: not applicable description: WithBitMap is a macro facility that sets up the drawing environment such that any drawing commands in the statement following the macro instantiation will draw into the bitmap provided as the first parameter. example application: In this example, we create a bitmap and use the WithBitMap macro to do some drawing in it. { BitMap *bits=NULL; BitMapPort *bmp; bits = NewBitMap(100, 100); if (bits == NULL) goto my_error_handler; WithBitMap(bits, bmp) { MoveTo(10,10); TextFont(geneva); TextSize(12); DrawString("\pHello World"); } my_error_handler: if (bits != NULL) KillBitMap(bits); } notes: none. PlotBitMap formal declaration: void PlotBitMap(BitMap* bits, short h, short v); arguments: bits a bitmap pointer h the horizontal location where the bitmap is drawn v the horizontal location where the bitmap is drawn mode transfer mode passed to copybits return value: none. description: PlotBitMap provides a simple interface for drawing a bitmap in the current grafport. The bitmap is drawn with the top left corner aligned with the point (h,v) using the indicated transfer mode. example application: In this example, we create a bitmap and use the WithBitMap macro to do some drawing in it, and then we copy the result to the current grafport at the location (75, 23) using the PlotBitMap routine. { BitMap *bits=NULL; BitMapPort *bmp; bits = NewBitMap(100, 100); if (bits == NULL) goto my_error_handler; WithBitMap(bits, bmp) { MoveTo(10,10); TextFont(geneva); TextSize(12); DrawString("\pHello World"); } PlotBitMap(bits, 75, 23, srcCopy); my_error_handler: if (bits != NULL) KillBitMap(bits); } notes: PlotBitMap calls CopyBits. StringToBitMap formal declaration: BitMap* StringToBitMap(short font, short size, short face, StringPtr s); arguments: font a font number size the font size face the font style (normal,bold,italic,underline,outline,shadow,condense,extend) s a pointer to a pascal string return value: a bitmap pointer description: StringToBitMap converts the string pointed to by s into a bitmap drawing the string onto an appropriately sized bitmap for the given font, size, and style(face). StringToBitMap is useful for converting strings to bitmap so rotation can be applied with RotateRight or RotateLeft before it is displayed. StringToBitMap preserves the current grafport. example application: In this example, we create a bitmap pointer containing the string "\pHello World" (using bold, underlined, 24 point geneva font), rotate it 90 degrees to the right, and draw the result in the current grafport at the location (110,34) using the PlotBitMap routine. { BitMap *bits = NULL, *right_bits = NULL; bits = StringToBitMap(geneva, 24, bold + underlined, "\pHello World"); if (bits == NULL) goto my_error_handler; right_bits = RotateRight(bits); if (right_bits == NULL) goto my_error_handler; PlotBitMap(right_bits, 110, 34); my_error_handler: if (bits != NULL) KillBitMap(bits); if (right_bits != NULL) KillBitMap(right_bits); } notes: none. file BitMap.txt Copyright (C) 1996 by John Montbriand. All Rights Reserved. end of file